Repository navigation
feat: durable approval plans, events and traceable run errors - #7
Merged
Merged
Conversation
agent.Plans is the approval API: List (the inbox), Get, Approve, Reject and Resume. A plan carries its status, expiry, request, run ID, each applied call's result and a history of every change. Decisions are a compare-and-set on the stored version, so a plan applies once across replicas; expiry is checked on read; applying records each result before the next call, so a crash resumes instead of losing the plan. Errors name the plan and its state. agent/sqlplans stores plans in SQLite or Postgres through database/sql, and agent/plantest is the contract every store passes. Options.OnEvent reports every step of a run with its run ID, LogEvents sends events to slog, and every error Run returns except *Pending is an *agent.Error with the run ID and the failing stage. Replaces NewMemoryPlans and ApplyPlan, which were never released.
Plans live in the app's SQLite file. The Approvals page lists every plan from GET /api/plans with its expiry and history, and the chat shows the same view for a plan it just held. Approve and reject answer 409 for a decided plan and 410 for an expired one, with the plan as it stands.
Approving writes is rewritten around agent.Plans: setup, states, what is guaranteed and the errors each situation returns. A new observability page covers events, LogEvents, agent.Error and adapting events to tracing. Adds ADR 0009 and the durable-plans milestone.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #6.
Problem
In #6, a write that needs approval is held in a plan, but the plan only lived as long as the response that carried its ID:
When a run failed, nothing tied its error, its logs and its plan together.
Solution
A plan is a row in a database, not a process (ADR 0009). There is no actor framework and no workflow engine.
agent.PlanshasList(the inbox),Get,Approve,RejectandResume.pending → applying → applied | failed, orrejected/expired. Every change is recorded inHistorywith its time, who made it and a note.expiredwith an event. No background job.Resumecontinues from the first call with no recorded result.plan 3f2a… is already applied (by ada at …)orplan 3f2a…: call 2 of 3 (tasks.delete): …. They wrapErrNoPlan,ErrPlanExpiredorErrPlanDecided.agent.PlanStoreis a four-method port.agent/sqlplansimplements it for SQLite and Postgres using onlydatabase/sql, so it imports no driver.agent/plantest.Runis the contract test every store passes.Options.OnEventreceives oneagent.Eventper step of a run or plan, each carrying the run ID.agent.LogEventssends them tolog/slog. Every errorRunreturns, except*Pending, is an*agent.Errorwith the run ID and the stage that failed.Result.RunIDandPlan.RunIDcomplete the link.GET /api/plansand an Approvals page showing each plan's expiry and history. Approve and reject return 409 for an already-decided plan and 410 for an expired one, along with the plan as it stands.NewMemoryPlansandApplyPlanfrom #6 are replaced; neither was released.Verification
make test: buf lint,go test ./..., the env check, and the consumer check (agent/sqlplansbuilds withCGO_ENABLED=0).go test -race ./agent/...and the taskreport server tests.plantestcontract on the memory store, on SQLite (including a plan surviving a reopen), and on Postgres 17 in Docker.make test-postgresnow runs the Postgres plan test too.Approveon a plan that was already applying went through, which could have run its calls twice.GET /api/plans, approved (pending → applying → applied), and refused with 409 the second time. The log lines carried the run and plan IDs.TestRunReportsWhereTheTimeWentfailed once under a full parallelgo test ./...and then passed 200 of 200 runs, both on this branch and onmain. Its fakes are instant, and the Apple Silicon clock advances in roughly 42ns steps, so a step that fast can measure as zero. It's an existing flake and is not addressed here.Not in this PR
OnEvent).plan.heldevent.apply_planover MCP.